2020.2 (latest)

Upgrading

On this page:

Upgrade IAP (2018.x to 2020.x)

Upgrade Guide (2018.x → 2020.x)

This document explains how to upgrade your IAP software from release version 2018.x to 2020.x.

Notes:

  • Major changes to be aware of prior to upgrading the Itential Automation Platform (IAP) are discussed in the Product Notices section.
  • All steps must be completed for the upgrade process to succeed.

Version Info

Release Type Pronghorn Upgrade - Major
Current Version 2018.3.X
New Version 2020.1.X
Restart Required Yes

Nomenclature

Name Purpose Default / Example
MONGO PORT Port used by Mongo 27018
PRONGHORN_HOME Pronghorn Install Directory /opt/pronghorn
PRONGHORN_LOG Pronghorn Install Directory var/log/pronghorn
PRONGHORN DB Pronghorn Mongo Database. pronghorn
BACKUP LOC Location of backup files none
IAP 2019.2 Version Directory of old IAP itential-bundle-5-20192_2019.2.12
IAP 2019.3 Version Directory of new IAP itential-bundle-5-20193_2019.3.6
build-id Build version of IAP itential-bundle-5-20201_2020.1.2.linux.x86_64

Pre-Migration Steps

  • Refer to the PreCheck guide for the necessary steps to perform a backup and other essential pre-migration tasks.

Migration Steps

The information in this section outlines how to migrate IAP.

Note: Some processes are indepenent and can be performed in parallel by multiple engineers. Be sure, however, to complete all steps within a given process before proceeding to the next non-parallel process.

Pre-Migration Verification

Alert Before continuing any further, verify all migration steps have been completed.

  • Have Mongo and Pronghorn backups been completed?
  • Have NSO backups been taken?
  • Have all running Pronghorn Jobs been paused/canceled/or on manual tasks?
  • Has outage notification start been sent?

Shutdown IAP

Run the following to stop IAP:

  1. SSH into all Pronghorn servers and perform the following to stop Pronghorn.

    • sudo systemctl stop pronghorn

  2. Verify Pronghorn is stopped on all servers.

    • ps -ef|grep Pronghorn

Version Verification

Alert Before continuing any further, verify all migration steps have been completed.

  • Is Redis showing version 5.0.10?
  • Is the node.js version showing 12.20.1?
  • Is node package manager (NPM) showing version 6.14.8?
  • Is Mongo running version 4.2.11?

Update AAA Authentication

Versions of IAP prior to the 2018.3.21 maintenance release contain a security vulnerability due to the Local AAA adapter's dependency on the MongoDB Node.js driver. Versions of MongoDB prior to 3.1.13 include a DOS security vulnerability (Denial of Service). Consequently, that dependency was replaced with @itential/database, which requires a different set of database properties in the Local AAA service_config. Itential encourages everyone to install this patch to avoid the potential security risk.

Below is an example of the Local AAA service_config with database properties.

{
  "id": "Local AAA",
  "type": "local_aaa",
  "properties": {
    "database": {
    "db": "LocalAAA",
      "url": "mongodb://mongo.example.com:27017/?replicaSet=rs_pronghorn",
      "ssl": {
        "enabled": true,
        "sslValidate": true,
        "sslCA": "/opt/data/mongodb/ssl/mongodb_rootCA.pem",
        "acceptInvalidCerts": false,
        "checkServerIdentity": true
      },
      "replSet": { "enabled": true },
      "credentials": {
         "dbAuth": true,
         "user": "<place_username_here>",
         "passwd": "<place_password_here"
        }
    }
  },
  "brokers": [ "aaa" ]
}

Configure Your Local AAA Settings

  • Use the mongoProps settings from your environment to populate the settings object above within the LocalAAA service. The db parameter must be set to "LocalAAA" as shown in the above example.

    Note: Itential only recommends the use of Local AAA adapter in non-production environments, which should further mitigate the impact of this change.

Upgrade Pronghorn (IAP)

  • Refer to the Upgrade Wizard for the necessary steps to update all instances of Pronghorn (IAP).

Restart & Postcheck Verification

  • Refer to the PostCheck guide for the necessary steps to restart IAP and verify accessibility to the applications.

Rollback Instructions

  • Refer to the Rollback guide for the necessary steps to bring your system back to the previous version.

Common Errors

  • Refer to the Common Errors guide for examples and explanations on some of the more frequent errors you may encounter in the software upgrade.